﻿<h1>Goroutines, Deferred Function Calls and Panic/Recover</h1>

<p>
This article will introduce goroutines and deferred function calls.
Goroutine and deferred function call are two unique features in Go.
This article also explains panic and recover mechanism.
Not all knowledge relating to these features is covered in this
article, more will be introduced in future articles.
</p>

<a class="anchor" id="goroutine"></a>
<h3>Goroutines</h3>

<div>
<p>
Modern CPUs often have multiple cores, and some CPU cores support hyper-threading.
In other words, modern CPUs can process multiple instruction pipelines simultaneously.
To fully use the power of modern CPUs,
we need to do concurrent programming in coding our programs.
</p>

<p>
Concurrent computing is a form of computing in which
several computations are executed during overlapping time periods.
The following picture depicts two concurrent computing cases.
In the picture, A and B represent two separate computations.
The second case is also called parallel computing,
which is special concurrent computing.
In the first case, A and B are only in parallel during a small piece of time.

<div class="text-center">
<img src="res/concurrent-vs-parallel.png" alt="concurrent and parallel"></img>
</div>
</p>

<p>
Concurrent computing may happen in a program, a computer, or a network.
In Go 101, we only talk about program-scope concurrent computing.
Goroutine is the Go way to create concurrent computations in Go programming.
</p>

<p>
Goroutines are also often called green threads.
Green threads are maintained and scheduled by
the language runtime instead of the operating systems.
The cost of memory consumption and context switching,
of a goroutine is much lesser than an OS thread.
So, it is not a problem for a Go program to maintain tens of thousands
goroutines at the same time, as long as the system memory is sufficient.
</p>

<p>
Go doesn't support the creation of system threads in user code.
So, using goroutines is the only way to do (program scope) concurrent programming in Go.
</p>

<p>
Each Go program starts with only one goroutine, we call it the main goroutine.
A goroutine can create new goroutines.
It is super easy to create a new goroutine in Go,
just use the keyword <code>go</code> followed by a function call.
The function call will then be executed in a newly created goroutine.
The new created goroutine will exit alongside the exit of the called function.
</p>

All the result values of a goroutine function call
(if the called function returns values)
must be discarded in the function call statement.
The following is an example which creates two new goroutines
in the main goroutine.
In the example, <code>time.Duration</code> is a custom type defined
in the <code>time</code> standard package.
Its underlying type is the built-in type <code>int64</code>.
Underlying types will be explained in <a href="type-system-overview.html#underlying-type">the next article</a>.

<pre class="line-numbers"><code class="language-go">package main

import (
	"log"
	"math/rand"
	"time"
)

func SayGreetings(greeting string, times int) {
	for i := 0; i < times; i++ {
		log.Println(greeting)
		d := time.Second * time.Duration(rand.Intn(5)) / 2
		time.Sleep(d) // sleep for 0 to 2.5 seconds
	}
}

func main() {
	rand.Seed(time.Now().UnixNano())
	log.SetFlags(0)
	go SayGreetings("hi!", 10)
	go SayGreetings("hello!", 10)
	time.Sleep(2 * time.Second)
}
</code></pre>

Quite easy. Right? We do concurrent programming now!
The above program may have three user-created goroutines running
simultaneously at its peak during run time.
Let's run it. One possible output result:

<pre class="output"><code>hi!
hello!
hello!
hello!
hello!
hi!
</code></pre>

<p>
</p>

<p>
When the main goroutine exits, the whole program also exits,
even if there are still some other goroutines which have not existed yet.
</p>

<p>
Unlike previous articles, this program uses the <code>Println</code>
function in the <code>log</code> standard package instead of the
corresponding function in the <code>fmt</code> standard package.
The reason is the print functions in the <code>log</code> standard
package are synchronized (the next section will explain what are synchronizations),
so the texts printed by the two goroutines
will not be messed up in one line (though the chance of the printed texts
being messed up by using the print functions in the <code>fmt</code>
standard package is very small for this specific program).
</p>

</div>

<a class="anchor" id="synchronization"></a>
<h3>Concurrency Synchronization</h3>

<div>

Concurrent computations may share resources, generally memory resource.
There are some circumstances may happen in a concurrent computing.
<ul>
<li>
	In the same period of one computation is writing data to a memory segment,
	another computation is reading data from the same memory segment.
	Then the integrity of the data read by the other computation might be not preserved.
</li>
<li>
	In the same period of one computation is writing data to a memory segment,
	another computation is also writing data to the same memory segment.
	Then the integrity of the data stored at the memory segment might be not preserved.
</li>
</ul>

<p>
These circumstances are called data races. One of the duties in concurrent
programming is to control resource sharing among concurrent computations,
so that data races will never happen.
The ways to implement this duty are called concurrency synchronizations,
or data synchronizations, which will be introduced one by one in later Go 101 articles.
</p>

Other duties in concurrent programming include
<ul>
<li>
	determine how many computations are needed.
</li>
<li>
	determine when to start, block, unblock and end a computation.
</li>
<li>
	determine how to distribute workload among concurrent computations.
</li>
</ul>

<p>
The program shown in the last section is not perfect.
The two new goroutines are intended to print ten greetings each.
However, the main goroutine will exit in two seconds,
so many greetings don't have a chance to get printed.
How to let the main goroutine know when the two new goroutines
have both finished their tasks?
We must use something called concurrency synchronization techniques.
</p>

<p>
Go supports several
<a href="concurrent-synchronization-overview.html">concurrency synchronization techniques</a>.
Among them, <a href="channel.html">the channel technique</a> is the most unique and popularly used one.
However, for simplicity purpose, here we will use another technique,
the <code>WaitGroup</code> type in the <code>sync</code> standard package,
to synchronize the executions between the two new goroutines and the main goroutine.
</p>

The <code>WaitGroup</code> type has three methods (special functions, will be explained later):
<code>Add</code>, <code>Done</code> and <code>Wait</code>.
This type will be explained in detail later in another article.
Here we can simply think
<ul>
<li>
	the <code>Add</code> method is used to register the number of new tasks.
</li>
<li>
	the <code>Done</code> method is used to notify that a task is finished.
</li>
<li>
	and the <code>Wait</code> method makes the caller goroutine become blocking until all registered tasks are finished.
</li>
</ul>

Example:
<pre class="line-numbers"><code class="language-go">package main

import (
	"log"
	"math/rand"
	"time"
	"sync"
)

var wg sync.WaitGroup

func SayGreetings(greeting string, times int) {
	for i := 0; i < times; i++ {
		log.Println(greeting)
		d := time.Second * time.Duration(rand.Intn(5)) / 2
		time.Sleep(d)
	}
	// Notify a task is finished.
	wg.Done() // <=> wg.Add(-1)
}

func main() {
	rand.Seed(time.Now().UnixNano())
	log.SetFlags(0)
	wg.Add(2) // register two tasks.
	go SayGreetings("hi!", 10)
	go SayGreetings("hello!", 10)
	wg.Wait() // block until all tasks are finished.
}
</code></pre>

<p>
Run it, we can find that, before the program exits,
each of the two new goroutines prints ten greetings.
</p>

</div>

<a class="anchor" id="states-of-goroutine"></a>
<h3>Goroutine States</h3>

<div>
<p>
The last example shows that a live goroutine may stay in (and switch between)
two states, <b>running</b> and <b>blocking</b>.
In that example, the main goroutine enters the blocking state when the
<code>wg.Wait</code> method is called, and enter running state again
when the other two goroutines both finish their respective tasks.
</p>

<p>
The following picture depicts a possible lifecycle of a goroutine.

<div class="text-center">
<img src="res/goroutine-states.png" alt="goroutine states"></img>
</div>
</p>

<p>
Note, a goroutine in sleeping (by calling <code>time.Sleep</code> function)
or waiting the response of a system call or a network connection
is viewed as staying in running state.
</p>

<p>
When a new goroutine is created, it will enter running state automatically.
Goroutines can only exit from running state, and never from blocking state.
If, for any reason, a goroutine stays in blocking state forever,
then it will never exit.
Such cases, except some rare ones, should be avoided in concurrent programming.
</p>

<p>
A blocking goroutine can only be unblocked by
an operation made in another goroutine.
If all goroutines in a Go program are in blocking state,
then all of them will stay in blocking state forever.
This can be viewed as an overall deadlock.
When this happens in a program, the standard Go runtime
will try to crash the program.
</p>

The following program will crash, after two seconds:
<pre class="line-numbers"><code class="language-go">package main

import (
	"sync"
	"time"
)

var wg sync.WaitGroup

func main() {
	wg.Add(1)
	go func() {
		time.Sleep(time.Second * 2)
		wg.Wait()
	}()
	wg.Wait()
}
</code></pre>

The output:
<pre class="output"><code>fatal error: all goroutines are asleep - deadlock!

...
</code></pre>

<p>
Later, we will learn more operations which will make goroutines enter blocking state.
</p>

</div>

<h3>Goroutine Schedule</h3>

<p>
Not all goroutines in running state are being executed at a given time.
At any given time, the maximum number of goroutines being executed will
not exceed the number of the logical CPUs available for the current program.
We can call the <a href="https://golang.org/pkg/runtime/#NumCPU"><code>runtime.NumCPU</code></a>
function to get the number of logical CPUs available for the current program.
Each logical CPU can only execute one goroutine at any given time.
Go runtime must frequently switch execution contexts between goroutines
to let each running goroutine have a chance to execute.
This is similar to how operating systems switch execution contexts between OS threads.
</p>

<p>
The following picture depicts a more detailed possible lifecycle for a goroutine.
In the picture, the running state is divided into several more sub-states.
A goroutine in the queuing sub-state is waiting to be executed.
A goroutine in the executing sub-state may enter the queuing sub-state
again when it has been executed for a while (a very small piece of time).

<div class="text-center">
<img src="res/goroutine-schedule.png" alt="goroutine sub-states"></img>
</div>
</p>

<p>
Please note, for simplicity, the sub-states shown in the above
picture will be not mentioned in other articles in Go 101.
And again, in Go 101, the sleeping and system calling sub-states are not viewed
as sub-states of the blocking state.
</p>

<p>
The standard Go runtime adopts the
<a href="https://docs.google.com/document/d/1TTj4T2JO42uD5ID9e89oa0sLKhJYD0Y_kqxDv3I3XMw">M-P-G model</a>
to do the goroutine schedule job,
where <b>M</b> represents OS threads,
<b>P</b> represents logical/virtual processors (not logical CPUs)
and <b>G</b> represents goroutines.
Most schedule work is made by logical processors (<b>P</b>s),
which act as brokers by attaching goroutines (<b>G</b>s) to OS threads (<b>M</b>s).
Each OS thread can only be attached to at most one goroutine at any given time,
and each goroutine can only be attached to at most one OS thread at any given time.
A goroutine can only get executed when it is attached to an OS thread.
A goroutine which has been executed for a while will try to detach itself from the corresponding OS thread,
so that other running goroutines can have a chance to get attached and executed.
</p>

<p>
At runtime. we can call the <a href="https://golang.org/pkg/runtime/#GOMAXPROCS"><code>runtime.GOMAXPROCS</code></a>
function to get and set the number of logical processors (<b>P</b>s).
For the standard Go runtime, before Go 1.5, the default initial value of this number is <code>1</code>,
but since Go 1.5, the default initial value of this number is equal to
the number of logical CPUs available for the current running program.
The default initial value (the number of logical CPUs) is the best choice for most programs.
But for some file IO heavy programs, a <code>GOMAXPROCS</code> value larger than <code>runtime.NumCPU()</code> may be helpful.
</p>

<p>
The default initial value of <code>runtime.GOMAXPROCS</code> can also be set through the <code>GOMAXPROCS</code> environment variable.
</p>

<p>
At any time, the number of goroutines in the executing sub-state is no more than
the smaller one of <code>runtime.NumCPU</code> and <code>runtime.GOMAXPROCS</code>.
</p>

<a class="anchor" id="defer"></a>
<h3>Deferred Function Calls</h3>

<div>
<p>
A deferred function call is a function call which follows a <code>defer</code> keyword.
Like goroutine function calls,
all the result values of the function call (if the called function returns values)
must be discarded in the function call statement.
</p>

<p>
When a function call is deferred, it is not executed immediately.
It will be pushed into a defer-call stack maintained by its caller goroutine.
After a function call <code>fc(...)</code> returns and enters its
<a href="function-declarations-and-calls.html#exiting-phase">exiting phase</a>,
all the deferred function calls pushed in the function call (<code>fc...</code>)
(which has not exited yet) will be executed,
by their inverse order being pushed into the defer-call stack.
Once all these deferred calls are executed,
the function call <code>fc(...)</code> exits.
</p>

Here is a simple example to show how to use deferred function calls.

<pre class="line-numbers"><code class="language-go">package main

import "fmt"

func main() {
	defer fmt.Println("The third line.")
	defer fmt.Println("The second line.")
	fmt.Println("The first line.")
}
</code></pre>

The output:
<pre class="output"><code>The first line.
The second line.
The third line.
</code></pre>

<p>
</p>

In fact, each goroutine maintains two call stacks, the normal-call stack and defer-call stack.
<ul>
<li>
	For two adjacent function calls in the normal-call stack of a goroutine,
	the later pushed one is called by the earlier pushed one.
	The earliest function call in the normal-call stack is the entry call
	of the goroutine.
</li>
<li>
	The function calls in the defer-call stack have no calling relations.
</li>
</ul>

Here is another example which is a little more complex.
The example will print <code>0</code> to <code>9</code>,
each per line, by their natural order.
<pre class="line-numbers"><code class="language-go">package main

import "fmt"

func main() {
	defer fmt.Println("9")
	fmt.Println("0")
	defer fmt.Println("8")
	fmt.Println("1")
	if false {
		defer fmt.Println("not reachable")
	}
	defer func() {
		defer fmt.Println("7")
		fmt.Println("3")
		defer func() {
			fmt.Println("5")
			fmt.Println("6")
		}()
		fmt.Println("4")
	}()
	fmt.Println("2")
	return
	defer fmt.Println("not reachable")
}
</code></pre>

<p>
</p>
</div>

<a class="anchor" id="defer-modify-results"></a>
<h3>Deferred Function Calls Can Modify the Named Return Results of Nesting Functions</h3>

<div>
For example,
<pre class="line-numbers"><code class="language-go">package main

import "fmt"

func Triple(n int) (r int) {
	defer func() {
		r += n // modify the return value
	}()

	return n + n // <=> r = n + n; return
}

func main() {
	fmt.Println(Triple(5)) // 15
}
</code></pre>
</div>

<h3>The Necessary and Benefits of the Deferred Function Feature</h3>

<p>
In the above examples, the deferred function calls are not absolutely necessary.
However, the deferred function call feature is a necessary feature for the
panic and recover mechanism which will be introduced below.
</p>

<p>
Deferred function calls can also help us write more clean and robust code.
We can read more code examples by using deferred function calls
and learn more details on deferred function calls in the article
<a href="defer-more.html">more about deferred functions</a> later.
</p>

<a class="anchor" id="argument-evaluation-moment"></a>
<h3>The Evaluation Moment of the Arguments of Deferred and Goroutine Function Calls</h3>

<div>
The arguments of a deferred function call or a goroutine function call are all
evaluated at the moment when the function call is invoked.
<ul>
<li>
	For a deferred function call, the invocation moment is the moment
	when it is pushed into the defer-call stack of its caller goroutine.
</li>
<li>
	For a goroutine function call, the invocation moment is
	the moment when the corresponding goroutine is created.
</li>
</ul>

<p>
The expressions enclosed within the body of an anonymous function call,
whether the call is a general call or a deferred/goroutine call,
will not be evaluated at the moment when the anonymous function call is invoked.
</p>

Here is an example.
<pre class="line-numbers"><code class="language-go">package main

import "fmt"

func main() {
	func() {
		for i := 0; i < 3; i++ {
			defer fmt.Println("a:", i)
		}
	}()
	fmt.Println()
	func() {
		for i := 0; i < 3; i++ {
			defer func() {
				fmt.Println("b:", i)
			}()
		}
	}()
}
</code></pre>

Run it. The output:
<pre class="output"><code>a: 2
a: 1
a: 0

b: 3
b: 3
b: 3
</code></pre>

<p>
The first loop prints <code>i</code> as <code>2</code>, <code>1</code> and <code>0</code> as a sequence.
The second loop always prints <code>i</code> as <code>3</code>,
for when the three <code>fmt.Println</code> calls in the deferred anonymous calls are invoked,
the value of the loop variable <code>i</code> becomes <code>3</code>.
</p>

To make the second loop print the same result as the first one,
we can modify the second loop as

<pre class="line-numbers"><code class="language-go">		for i := 0; i < 3; i++ {
			defer func(i int) {
				// The "i" is the input parameter.
				fmt.Println("b:", i)
			}(i)
		}
</code></pre>

or

<pre class="line-numbers"><code class="language-go">		for i := 0; i < 3; i++ {
			i := i
			defer func() {
				// The "i" is not the loop variable.
				fmt.Println("b:", i)
			}()
		}
</code></pre>

<p>
</p>

The same argument valuation moment rules are for goroutine function calls.
The following program will output <code>123 789</code>.

<pre class="line-numbers"><code class="language-go">package main

import "fmt"
import "time"

func main() {
	var a = 123
	go func(x int) {
		time.Sleep(time.Second)
		fmt.Println(x, a) // 123 789
	}(a)

	a = 789

	time.Sleep(2 * time.Second)
}
</code></pre>

<p>
By the way, it is not a good idea to do synchronizations by using <code>time.Sleep</code> calls in formal projects.
If the program runs on a computer which CPUs are occupied by many other
programs running on the computer, the newly created goroutine may never
get a chance to execute before the program exits.
We should use the concurrency synchronization techniques introduced in the article
<a href="concurrent-synchronization-overview.html">concurrency synchronization overview</a>
to do synchronizations in formal projects.
</p>

</div>

<a class="anchor" id="panic-recover"></a>
<h3>Panic and Recover</h3>

<p>
Go doesn't support exception throwing and catching,
instead explicit error handling is preferred to use in Go programming.
In fact, Go supports an exception throw/catch alike mechanism.
The mechanism is called panic/recover.
</p>

<p>
We can call the built-in <code>panic</code> function to create a panic
to make the current goroutine enter panicking status.
The panic is only alive within the current goroutine.
</p>

<p>
Panicking is another way to make a function return.
Once a panic is produced in a function call, the function call returns immediately
and enters its exiting phase. The deferred function calls pushed in the defer-call stack
will get executed, by their inverse order being pushed.
</p>

<p>
By calling the built-in <code>recover</code> function in a deferred call,
an alive panic in the current goroutine can be removed
so that the current goroutine will enter normal calm status again.
</p>

<p>
If a panicking goroutine exits without being recovered, it will make the whole program crash.
</p>

The built-in <code>panic</code> and <code>recover</code> functions are
declared as
<pre class="line-numbers"><code class="language-go">func panic(v interface{})
func recover() interface{}
</code></pre>

<p>
Interface types and values will be explained in the article
<a href="interface.html">interfaces in Go</a> later.
Here, we just need to know that the blank interface type
<code>interface{}</code> can be viewed as the <code>any</code> type
or the <code>Object</code> type in many other languages. In other words,
we can pass a value of any type to a <code>panic</code> function call.
</p>

<p>
The value returned by a <code>recover</code> function call is the value
a <code>panic</code> function call consumed.
</p>

The example below shows how to create a panic and how to recover from it.

<pre class="line-numbers"><code class="language-go">package main

import "fmt"

func main() {
	defer func() {
		fmt.Println("exit normally.")
	}()
	fmt.Println("hi!")
	defer func() {
		v := recover()
		fmt.Println("recovered:", v)
	}()
	panic("bye!")
	fmt.Println("unreachable")
}
</code></pre>

The output:

<pre class="output"><code>hi!
recovered: bye!
exit normally.
</code></pre>

<p>
</p>

Here is another example which shows a panicking goroutine exits without being recovered.
So the whole program crashes.

<pre class="line-numbers"><code class="language-go">package main

import (
	"fmt"
	"time"
)

func main() {
	fmt.Println("hi!")

	go func() {
		time.Sleep(time.Second)
		panic(123)
	}()

	for {
		time.Sleep(time.Second)
	}
}
</code></pre>

The output:

<pre class="output"><code>hi!
panic: 123

goroutine 5 [running]:
...
</code></pre>

<p>
</p>

Go runtime will create panics for some circumstances,
such as dividing an integer by zero. For example,

<pre class="line-numbers"><code class="language-go">package main

func main() {
	a, b := 1, 0
	_ = a/b
}
</code></pre>

The output:

<pre class="output"><code>panic: runtime error: integer divide by zero

goroutine 1 [running]:
...
</code></pre>

<p>
</p>

<p>
More runtime panic circumstances will be mentioned
in later Go 101 articles.
</p>

<p>
Generally, panics are used for logic errors, such as human careless errors.
Logic errors are the errors which should never happen at run time.
If they are happen, there must be bugs in the code.
On the other hand, non-logic errors are the errors
which are hard to absolutely avoid at run time.
In other words, non-logic errors are errors happening in reality.
Such errors should not cause panics and should be explicitly returned and handled properly.
</p>

<p>
We can learn <a href="panic-and-recover-use-cases.html">some panic/recover use cases</a>
and <a href="panic-and-recover-more.html">more about panic/recover mechanism</a> later.
</p>

<h3>Some Fatal Errors Are Not Panics and They Are Unrecoverable</h3>

<p>
For the standard Go compiler, some fatal errors,
such as stack overflow and out of memory are not recoverable.
Once they occur, program will crash.
</p>



